feat(ai): support complete model provider surface - #385

Purpose

Complete issue 10 by implementing the full model provider, authentication, catalog, native codec, configured endpoint, and provider management surface through the existing ModelProvider contract. This matters because Axl previously exposed only an Azure-focused path and could not safely select, authenticate, discover, or operate the required provider set through daemon-owned product surfaces.

Fixes

Fixes #10

Approach

Implemented and registered all 41 provider identities with model-selected API dialects, provider-owned authentication, explicit dynamic catalog refresh, and synchronous offline static catalogs. Added the 11 required native codec surfaces, shared request preparation, deterministic provider transports, cloud and subscription authentication, daemon-owned provider management, typed SDK methods, and provider-neutral CLI and TUI workflows.

Static catalog inputs are checked-in provider-scoped JSON Lines shards with checksum-bearing provenance manifests. Generation is local and deterministic, producing a compact index plus 36 provider shards. The semantic baseline remains 1,102 models with SHA-256 a5069e2017a50867f8c9846e05f56017cc037bdb4754c2aa97168746f886bc19.

Security boundaries remain fail closed. Credentials and prompt answers stay inside trusted provider and process-host adapters, provider listing has no credential or network side effects, cloud signing failures do not fall back to unsigned dispatch, and opaque continuation metadata is retained only for its exact provider, dialect, and model provenance.

The original implementation grouped related implementation, verification, documentation, catalog, and security work into coherent commits. Initial pull request CodeQL analysis identified two high-severity polynomial regular-expression findings in caller-controlled Azure and Radius base URL normalization. Commit 49f2adb replaces those expressions with bounded linear scans and adds long-input regressions. An unrelated draft replacement of repository development guidance in AGENTS.md was removed during final scope review.

Follow-up commit 22f65de retains Axl's ModelProvider contract and adds:

• Native ~/.axl/models.json with named providers, provider-scoped credentials, validated reasoning metadata, and explicit migration from custom-provider.json. Configuration edits currently require a daemon restart.
• Shared catalog normalization and policy for offline generation and explicit refresh of 35 models.dev-backed built-ins. The four existing dynamic catalogs retain provider discovery. Ant Ling and explicit custom model lists have no remote discovery.
• Pi-style inline login: authentication method, searchable provider list with status, and cancellable prompts with masked secrets. Browser opening remains in the trusted process host; prompt answers never enter daemon RPC or canonical history.
• Fixes for Node's pinned-DNS lookup callback shapes, named loopback providers, dispatch of refreshed Chat models, blank Enterprise-domain prompts, and aggregate refresh failures returning success.

The first-party image command remains a limitation. OpenRouter image generation is available through @axl/ai. Only Azure has been live-tested in this follow-up; the complete provider inventory is not a claim of production verification across every backend.

How was this tested?

Latest follow-up verification

• pnpm check: passed again before push, including formatting, lint, type checking, build, 818 tests (810 passed, 8 existing platform/environment skips), boundaries, and generated-file checks.
• pnpm check:generated: passed separately. The reviewed 1,102-model semantic baseline is unchanged.
• node --test --test-timeout=30000 packages/ai/test/transport-safety.test.ts packages/ai/test/catalog.test.ts packages/ai/test/models-config.test.ts packages/ai/test/azure-openai.test.ts: focused checks passed. Additional Azure reasoning coverage verifies all 66 bundled Azure models across seven thinking levels, 462 combinations.
• Built-CLI loopback inference and real PTY login smoke tests passed, including method/provider selection, Enterprise-domain prompts, secret masking, cancellation, and narrow-terminal resize.
• pnpm audit --audit-level high: passed with no known vulnerabilities.
• git diff --cached --check: passed.
• uvx --offline reuse --root <staged-snapshot> lint: passed for all 492 staged product files. Direct worktree REUSE checking flags six pre-existing, untracked scratch files under tmp/; they were not changed or committed.
• User-authorized live Azure smoke: the built CLI and daemon ran in a disposable Bubblewrap-enforced workspace using an isolated in-memory credential store. Catalog refresh returned 67 Azure models. gpt-5.6-luna returned exactly OK at requested/effective low with no clamping or tool calls. The verified call reported 195 input tokens, 5 output tokens, and catalog-derived cost of $0.000045. Credentials were absent from stdout, stderr, and canonical history; existing settings and credential files were hash-checked and unchanged.
• The live test first exposed the DNS callback defect. A real-socket regression now covers both Node lookup callback forms. Two minimal inference calls followed: the first exited successfully but the temporary reporter used incorrect event names; the corrected reporter verified the second call. No other provider inference was tested.
• A first aggregate run exposed picker-header clipping after the cursor correction. The implementation was fixed and the full checks subsequently passed. No valid test was weakened or skipped.

Earlier implementation verification

The results below describe earlier revisions of the PR. Those routine checks were local and deterministic and did not use live provider credentials.

• Node test runner over packages/ai/test/catalog.test.ts with a 30-second timeout: passed 7 of 7 tests, including provider counts, semantic baseline, provenance, offline behavior, and deterministic regeneration.
• pnpm check:generated: passed.
• Node test runner over packages/ai/test/*.test.ts with a 30-second timeout: passed 244 of 244 tests, including the exact 41-provider registration inventory.
• pnpm check: passed formatting and lint for 330 files, root type checking, the complete build, 749 tests with 741 passing and 8 environment-dependent skips, package boundaries, and generated-file checks. There were no failures or cancellations.
• reuse lint: passed, 490 of 490 files compliant.
• pnpm audit with the high severity threshold: passed with no known vulnerabilities.
• Git whitespace validation from origin/main through HEAD: passed.
• Corrected changed-file credential-pattern scan: passed with no matches.
• DCO and Conventional Commit audit: passed for all 18 feature commits.
• Initial pull request CodeQL check: failed with two high-severity polynomial regular-expression findings. After the final security correction, 19 focused Azure and remaining-provider tests, targeted Biome checks, AI type checking, and the complete repository gates passed. The replacement CodeQL check passed.
• Replacement pull request build check: the aggregate test process was canceled at the 10-minute job limit while running the TUI app suite, after all output through test 558 had passed. GitHub denied the failed-job rerun because the fork account lacks repository admin permission. This is the known aggregate TUI hang described below, not a reported assertion failure.
• Detached synthetic merge against origin/main at e98f686935199cd39738a34c32acd5bc398bf0a7: passed without conflicts, and the staged merge tree exactly matched the feature tree.

The repository has a known intermittent aggregate TUI timing and temporary-directory cleanup flake. It did not reproduce in the final 749-test run, so no focused retry was required. Earlier aggregate attempts and focused passing retries remain recorded in docs/model-provider-handoff.md. No test was skipped or weakened, no timeout was increased, and no ineffective runner change was retained.

Learning

The implementation and executable evidence are mapped in docs/provider-support/issue-10-completion.md and docs/provider-support/deterministic-verification.md. Provider setup, environment variables, endpoint and regional policy, catalog maintenance, compatibility controls, custom endpoints, and limitations are consolidated in docs/provider-support/provider-reference.md.

The compact catalog keeps source facts, Axl policy overlays, and generated runtime data separate. This preserves offline synchronous reads while making provenance and model changes reviewable by provider.

The follow-up compared Pi revision 6c87d9a026677b601e8278030dcf1ad97fe0bd86 read-only. Pi's user-authored models.json is separate from generated catalogs and its discovery cache. Its command is pi update --models, not pi --model refresh; it refreshes providers implementing discovery rather than regenerating every static provider. Axl adopts the interaction design and shares its own normalization, without copying Pi source or introducing another provider abstraction.

Checklist

• I reviewed the complete diff.
• I added or updated the smallest relevant test for behavior changes.
• I ran the relevant formatting, lint, type-check, test, boundary, and license checks.
• Every new file has SPDX metadata, directly or through REUSE.toml.
• Every commit has a matching DCO Signed-off-by trailer.
• UI changes include screenshots attached to the pull request, not committed to the repository.

The UI changes are terminal-only CLI and TUI workflows with deterministic transcript and integration coverage. No screenshot is attached, so the screenshot item remains unchecked rather than being claimed as complete.

Licenses

• models.dev factual model metadata: https://models.dev/api.json at repository revision 5c600a037417cf778ee6eb3ea2ce0f17abc12130, MIT, used for reduced provider-scoped static catalog inputs.
• Azure Identity: @azure/identity 4.13.2, MIT, used for Microsoft Entra credential acquisition.
• Google Auth Library: google-auth-library 11.0.2, Apache-2.0, used for Vertex ADC and service-account authentication.
• AWS credential provider and Smithy signing packages: versions pinned in packages/ai/package.json and pnpm-lock.yaml, Apache-2.0, used for the AWS credential chain and SigV4 request signing.

AI assistance

• Generative AI materially assisted this change. Original implementation: pi coding agent with azure-openai-responses/gpt-5.6-sol. Follow-up: pi coding agent; its model identifier was not available in the exported session metadata. Hari Srinivasan directed the follow-up and explicitly authorized publication.
• I manually reviewed, understood, and tested the generated work.